% cxref program README (c) Andrew M. Bishop 1995,96.

\documentstyle[doc/fonts,doc/page]{report}
\pagestyle{myheadings}
\begin{document}

\setcounter{secnumdepth}{3}
\setcounter{tocdepth}{3}

\setlength{\parindent}{0in}
\setlength{\tabcolsep}{0in}

\newcommand{\stt}{\small\tt}

\newenvironment{cxrefarglist}{\begin{list}{}{\leftmargin=2.25in \labelsep=0in \labelwidth=2.25in \itemsep=0pt \parsep=3pt \topsep=3pt}}{\end{list}}
\newcommand{\cxrefargitem}[1]{\item[\parbox{2.25in}{$\cdot$\hspace*{0.1in}{\stt #1}}]}

\newenvironment{cxreftabi}{\begin{tabular}{{p{5.0in}l}}}{\end{tabular}}
\newenvironment{cxreftabii}{\begin{tabular}{{p{0.75in}p{4.25in}l}}}{\end{tabular}}
\newenvironment{cxreftabiia}{\begin{tabular}{{p{2.5in}p{3.5in}}}}{\end{tabular}}
\newenvironment{cxreftabiib}{\begin{tabular}{{p{2.5in}p{2.5in}l}}}{\end{tabular}}
\newenvironment{cxreftabiii}{\begin{tabular}{{p{0.75in}p{2.25in}p{2.0in}l}}}{\end{tabular}}
\newcommand{\twocoltabiii}[1]{\multicolumn{2}{p{4.25in}}{#1}}

\newcommand{\cxreftabbreak}[1]{\end{#1}\vskip 0pt\begin{#1}}

\newcommand{\cxreffile}[1]{{\small\it (Section \ref{file_#1})}}
\newcommand{\cxreffunc}[2]{{\small\it (Section \ref{func_#1_#2})}}
\newcommand{\cxrefvar}[2]{{\small\it (Section \ref{var_#1_#2})}}
\newcommand{\cxreftype}[2]{{\small\it (Section \ref{type_#1_#2})}}

% Begin-Of-Doc

\chapter{C cross referencing tool ``cxref''}

A program that can automatically generate documentation and cross references
for a C program.

The input is any C program with appropriate comments and the output is \LaTeX
or HTML files.

\section{Program Options}

The name of the program is cxref.

\smallskip

\begin{tabular}{ll}
Usage: {\tt cxref} & \\
& {\tt filename [ ... filename]} \\
& {\tt [-Idirname]} \\
& {\tt [-Ddefine] [-Udefine]} \\
& {\tt [-CPP cpp\_program]} \\
& {\tt [-Odirname]} \\
& {\tt [-Nbasename]} \\
& {\tt [-all-comments]} \\
& {\tt [-xref[-all][-file][-func][-var][-type]]} \\
& {\tt [-warn[-all][-comment][-xref]]} \\
& {\tt [-index[-all][-file][-func][-var][-type]]} \\
& {\tt [-raw]} \\
& {\tt [-latex|-latex2e]} \\
& {\tt [-html]} \\
\end{tabular}

\begin{list}{}{\leftmargin=1in \labelwidth=2.5in}
\item[{\tt filename}]
The name of the file to document, any number of files may be
documented at a time.
\item[{\tt -Idirname}]
GCC option to specify the path for include files.
\item[{\tt -Ddefine}]
GCC option to define a pre-processor symbol.
\item[{\tt -Udefine}]
GCC option to undefine a pre-processor symbol.
\item[{\tt -CPP program}]
The name of the program to use instead of the compile time
default. The program must be able to perform all of the actions
that `gcc -E -C -dD' does to work. If the program takes
arguments then the whole thing needs to be in quotes so that it
is interpreted as a single argument to cxref.
\item[{\tt -Odirname}]
The name of a directory to use for the output \LaTeX files and
the location of the cross reference files that are created.
\item[{\tt -Nbasename}]
The name to use for the first part of the output and cross
reference files instead of cxref, the file extensions remain
the same.
\item[{\tt -all-comments}]
In case you are lazy and think that the existing comments might
work, (see below for description of special comments).
{\it[Danger! This option can produce weird results.]}
\item[{\tt -xref}]
Produce cross referencing information (see below).
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]    All cross references.
\item[{\tt -file}]   Cross references for files.
\item[{\tt -func}]   Cross references for functions.
\item[{\tt -var}]    Cross references for variables.
\item[{\tt -type}]   Cross references for types.
\end{list}
\item[{\tt -warn}]
Produce warnings, the options must be concatenated together:
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]       All warnings.
\item[{\tt -comment}]   Warn of missing comments.
\item[{\tt -xref}]      Warn of missing cross references.
\end{list}
\item[{\tt -index}]
Produce a cross reference index, the options must be
concatenated together:
\begin{list}{}{\leftmargin=1in \labelwidth=1in}
\item[{\tt -all}]    All indexes.
\item[{\tt -file}]   Index of files.
\item[{\tt -func}]   Index of functions.
\item[{\tt -var}]    Index of variables.
\item[{\tt -type}]   Index of types.
\end{list}
\item[{\tt -raw}]
Produce a raw form of output, not really of much use except
with -warn.
\item[{\tt -latex}]
Produce a \LaTeX file to document each of the source files and
also an extra file that includes each of these files.
\item[{\tt -latex2e}]
Produce the LaTeX file for use with the LaTeX2e version.
\item[{\tt -html}]
Produce an HTML file to document each of the source files and
a main file to reference each of these files.
\end{list}

\section{Program Documentation Comments}

The documentation for the program is produced from comments in the code that
are appropriatly formatted. The cross referencing comes from the code itself
and requires no extra work.

The special comments are ``/**** ****/'' (for a file) and ``/*++++ ++++*/'' (for a
data object) any number of ``*'' or ``+'' can be used inside of the standard ``/*''
and ``*/'' comment delimiters in the comments, they are ignored.

In any situation where a comment follows a ``,'', ``;'' or ``)'' separated only by
spaces and tabs, the comment is pushed to before the punctuation to apply to
the object there.

The program is implemented using a full ANSI C grammar parser with some GCC
extensions, this means that the style of the code is unimportant, only the
content and comments.

\section{Automated Comment Insertion}

To simplify the insertion of comments that will be parsed by cxref, the file
cxref.el provides a number of Emacs lisp functions. To use them add the line
{\tt (load "cxref")} to your ``.emacs'' file or type {\tt M-x load-file cxref.el} from
within Emacs.

The functions and key bindings are:
\begin{list}{}{\leftmargin=1.3in \labelwidth=2.5in}
\item[{\it Control-C Control-F}]
Adds file comments, a /** **/ header at the top of the
file and if it is a .h file then it also adds a \#ifndef,
\#define at the beginning and \#endif at the end to stop
multiple inclusions.
\item[{\it Control-C f}]
Adds comments to a function, the cursor must be on the
line containing the start of the function definition when
this function is called. The /*+ ... +*/ comment that is
added is of the header type (see the examples) not inline.
\item[{\it Control-C v}]
Adds a leading comment to the variable or other definition
on the current line.
\item[{\it Control-C e}]
Adds a trailing comment at the end of the line.
\item[{\it Control-C i}]
Adds an inline comment that is ignored by cxref.
\end{list}

\section{C Preprocessor}

To improve the output that is available a modified version of the GNU CPP V2.6.3
is supplied (named cxref-cpp).

Some comment styles are only available if cxref-cpp is used, see the ``Example
Special Comments'' section of this README.

The \#include filenames are also full pathnames if cxref-cpp is not used.

To enable this option, the Makefile for cxref must be modified when cxref is
compiled, the variable CPP\_TO\_USE must be set to point at the place where the
C preprocessor is to be installed. If CPP\_TO\_USE is defined to an empty value
then ``gcc -E -C -dD'' is used as the C preprocessor and the extra features are
not available.
To see which option is enabled, run cxref with no arguments, this prints the
name of the preprocessor that is used, if the command is ``cxref-cpp'' then the
option is enabled.

\section{Example Special Comments}

The file ``README.c'' is included in this document to show that the comments are
indeed seen in the code, the result of running this through cxref is also
included in this document.

The comments only available with the cxref-cpp pre-processor are indicated.

\section{Cross Referencing}

The cross referencing is performed for the following items
\begin{list}{}{\leftmargin=1in \labelwidth=1.5in}
\item[Files]
\begin{itemize}
\item The files that the current file is included in
(even when included via other files).
\end{itemize}
\item[\#includes]
\begin{itemize}
\item Files included in the current file.
\item Files included by these files etc.
\end{itemize}
\item[Variables]
\begin{itemize}
\item The location of the definition of external variables.
\item The files that have visibility of global variables.
\item The files / functions that use the variable.
\end{itemize}
\item[Functions]
\begin{itemize}
\item The file that the function is prototyped in.
\item The functions that the function calls.
\item The functions that call the function.
\item The files and functions that reference the function.
\item The variables that are used in the function.
\end{itemize}
\end{list}
Each of these items is cross referenced in the output.

The cross referencing uses files `cxref.variable', `cxref.function',
`cxref.include' and `cxref.typedef' in the output directory.

These are a complete list of the function and variable usage in the program and
could be used to generate a function call hierarchy or variable usage diagram
for example.

Two cxref passes of each file is needed, the first to build up the cross
referencing files and the second to use them.

{\it (The file names are different if the ``-N'' option is used.)}

\section{\LaTeX Output}

The default \LaTeX output is a file for each of the source files with one extra
file ``cxref.tex'' that includes each of the other files. This is to allow a
makefile to only update the changed files (although the references may require
all of the files to be checked again). When the cxref.tex file has been written
it can be modified by the user, any new files that are added are added at the
end before the table of contents, the rest of the file being unchanged.

The index is written to a file called ``cxref.apdx.tex'' and cxref.tex is updated
to refer to it.

Also written out are two \LaTeX style files ``page.sty'' and ``fonts.sty'', these use
a smaller margin and smaller font to allow more to appear on a page.

{\it (The file names ``cxref.tex'' and ``cxref.apdx.tex'' are different if the ``-N''
option is used.)}

\section{HTML Output}

The default HTML output is a file for each of the source files with one extra
file ``cxref.html'' that includes each of the other files. This is to allow a
makefile to only update the changed files (although the references may require
all of the files to be checked again). When the cxref.html file has been written
it can be modified by the user, any new files that are added are added at the
end before the table of contents, the rest of the file being unchanged.

The index is written to a file called ``cxref.apdx.html'' and cxref.html is
updated to refer to it.

{\it (The file names ``cxref.html'' and ``cxref.apdx.html'' are different if the ``-N''
option is used.)}

\section{AUTHOR and Copyright}

The cxref program was written by Andrew M. Bishop in 1995,96.

The cxref program is copyright Andrew M. Bishop 1995,96.

email: amb@gedanken.demon.co.uk [Please put cxref in the subject line]

The cxref program can be freely distributed according to the terms of the GNU
General Public License (see the file ``COPYING'').

\chapter{Example comments, ``README.c''}

% What a hack to load a file into a verbatim section!
% I have also had to rename README.c.tex to README_c.tex
% so that \input{README.c} does not do \input{README.c.tex} instead.

\def\endverbatim{\input{README.c}\endtrivlist}
\begin{verbatim}
\end{verbatim}

\chapter{cxref output for ``README.c''}

\input{README_c.tex}

% Contents

\markboth{Contents}{Contents}
\tableofcontents

% End-Of-Doc

\end{document}
